package org.io4j.data;

import java.nio.charset.Charset;
import java.util.List;

/**
 * A source of text that can be read from.
 */
public interface TextSource {

	/**
	 * Reads lines from this {@code TextSource} and returns them in the
	 * {@code List} using platform's default character set.
	 * 
	 * @return {@code List} of {@code String}s containing all lines
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	List<String> readLines();

	/**
	 * Reads lines from this {@code TextSource} and returns them in the
	 * {@code List} using character set provided.
	 * 
	 * @param charset
	 *           Character set to use
	 * @return {@code List} of {@code String}s containing all lines
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	List<String> readLines(Charset charset);

	/**
	 * Reads contents of this {@code TextSource} and returns them as {@code List}
	 * using platform's default character set.
	 * 
	 * @return text contents of the {@code Readable}
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	String readText();

	/**
	 * Reads contents of this {@code TextSource} and returns them as
	 * {@code String} using character set provided.
	 * 
	 * @param charset
	 *           Character set to use
	 * @return text contents of the {@code Readable}
	 * @throws DataTransferException
	 *            if an error occurred during the operation
	 */
	String readText(Charset charset);
}
